/*  ------------------------------------------------------------------------
	NQ Common Services Library
	
	Homepage: http://www.awzhome.de/
	------------------------------------------------------------------------
	
	The contents of this file are subject to the Mozilla Public License
	Version 1.1 (the "License"); you may not use this file except in
	compliance with the License. You may obtain a copy of the License at
	http://www.mozilla.org/MPL/
	
	Software distributed under the License is distributed on an "AS IS"
	basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See the
	License for the specific language governing rights and limitations
	under the License.
   
	The Original Code is code of NQ Common Services Library.

	The Initial Developer of the Original Code is Andreas Weizel.
	Portions created by the Initial Developer are
	Copyright (C) 2006-2012 Andreas Weizel. All Rights Reserved.
	
	Contributor(s): (none)
	
	Alternatively, the contents of this file may be used under the terms
	of the GNU General Public License Version 2.0 or later (the "GPL"),
	or the GNU Lesser General Public License Version 2.1 or later (the
	"LGPL"), in which case the provisions of the GPL or the LGPL are
	applicable instead of those above. If you wish to allow use of your
	version of this file only under the terms of the GPL or the LGPL and
	not to allow others to use your version of this file under the MPL,
	indicate your decision by deleting the provisions above and replace
	them with the notice and other provisions required by the GPL or the
	LGPL. If you do not delete the provisions above, a recipient may use
	your version of this file under the terms of any of the MPL, the GPL
	or the LGPL.
	------------------------------------------------------------------------
*/

using AWZhome.NQ.Core;
using System;

namespace AWZhome.NQ.CommonServices
{
	/// <summary>
	/// Interface for services managing the application's configuration.
	/// </summary>
	/// <remarks>
	/// Usually the service loads the configuration into an internal cache in 
	/// <see cref="AWZhome.NQ.CommonServices.IPersistManager.LoadConfiguration">LoadConfiguration</see>
	/// method and uses it for reading and writing operations. In 
	/// <see cref="AWZhome.NQ.CommonServices.IPersistManager.SaveConfiguration">SaveConfiguration</see>
	/// method that is called when the application ends the service saves the contents of the cache
	/// back to disk.
	/// </remarks>
	public interface IPersistManager
	{
		/// <summary>
		/// Returns the path where the NQ system saves the user's settings.
		/// </summary>
		string UserAppDataPath
		{
			get;
		}

		/// <summary>
		/// Returns the path where the NQ systems saves common settings.
		/// </summary>
		/// <remarks>
		/// In the current version of NQ Common Services this path is not used.
		/// </remarks>
		string CommonAppDataPath
		{
			get;
		}

		/// <summary>
		/// Creates a new connection profile in the setting file.
		/// </summary>
		/// <param name="profileName">Name of the profile.</param>
		/// <param name="protocolName">
		/// Name of the protocol, returned by the 
		/// <see cref="AWZhome.NQ.CommonServices.ISession.Protocol">Protocol</see> property of
		/// a session service.
		/// </param>
		/// <returns><c>True</c>, if the profile could be created successfully.</returns>
		bool AddProfile(string profileName, string protocolName);

		/// <summary>
		/// Removes a connection profile from setting file.
		/// </summary>
		/// <param name="profileName">Name of the profile to delete.</param>
		/// <param name="protocolName">
		/// Name of the protocol, returned by the 
		/// <see cref="AWZhome.NQ.CommonServices.ISession.Protocol">Protocol</see> property of
		/// a session service.
		/// </param>
		/// <returns><c>True</c>, if the profile could be removed successfully.</returns>
		bool RemoveProfile(string profileName, string protocolName);

		/// <summary>
		/// Renames a connection profile.
		/// </summary>
		/// <param name="oldProfile">Old name of the profile.</param>
		/// <param name="protocolName">
		/// Name of the protocol, returned by the 
		/// <see cref="AWZhome.NQ.CommonServices.ISession.Protocol">Protocol</see> property of
		/// a session service.
		/// </param>
		/// <param name="newProfile">New name of the profile</param>
		void RenameProfile(string oldProfile, string protocolName, string newProfile);

		/// <summary>
		/// Returns an array of the names of all connection profiles saved in the setting file.
		/// </summary>
		/// <returns>A string array of the profile names.</returns>
		string[] GetProfileList();

		/// <summary>
		/// Returns a list of the names of all containers saved in the setting file.
		/// </summary>
		/// <returns>A string array of the container names.</returns>
		string[] GetContainerList();

		/// <summary>
		/// Returns a setting from a connection profile.
		/// </summary>
		/// <param name="profile">The profile name.</param>
		/// <param name="protocolName">
		/// Name of the protocol, returned by the 
		/// <see cref="AWZhome.NQ.CommonServices.ISession.Protocol">Protocol</see> property of
		/// a session service.
		/// </param>
		/// <param name="settingName">Name of the setting parameter.</param>
		/// <returns>A <see cref="AWZhome.NQ.CommonServices.ConfigData">ConfigData</see> instance with the setting data.</returns>
		ConfigData GetProfileSetting(string profile, string protocolName, string settingName);

		/// <summary>
		/// Returns a list setting from a connection profile.
		/// </summary>
		/// <param name="profile">The profile name.</param>
		/// <param name="protocolName">
		/// Name of the protocol, returned by the 
		/// <see cref="AWZhome.NQ.CommonServices.ISession.Protocol">Protocol</see> property of
		/// a session service.
		/// </param>
		/// <param name="settingName">Name of the list setting parameter.</param>
		/// <returns>A list of <see cref="AWZhome.NQ.CommonServices.ConfigData">ConfigData</see> instances with the setting data.</returns>
		System.Collections.Generic.IList<ConfigData> GetProfileListSetting(string profile, string protocolName, string settingName);

		/// <summary>
		/// Sets a setting of a connection profile.
		/// </summary>
		/// <param name="profile">The profile name.</param>
		/// <param name="protocolName">
		/// Name of the protocol, returned by the 
		/// <see cref="AWZhome.NQ.CommonServices.ISession.Protocol">Protocol</see> property of
		/// a session service.
		/// </param>
		/// <param name="settingName">Name of the setting.</param>
		/// <param name="data">A <see cref="AWZhome.NQ.CommonServices.ConfigData">ConfigData</see> instance with the setting data.</param>
		/// <returns><c>True</c>, if the value is set successfully.</returns>
		bool SetProfileSetting(string profile, string protocolName, string settingName, ConfigData data);

		/// <summary>
		/// Sets a list setting of a connection profile.
		/// </summary>
		/// <param name="profile">The profile name.</param>
		/// <param name="protocolName">
		/// Name of the protocol, returned by the 
		/// <see cref="AWZhome.NQ.CommonServices.ISession.Protocol">Protocol</see> property of
		/// a session service.
		/// </param>
		/// <param name="settingName">Name of the setting.</param>
		/// <param name="data">A list of <see cref="AWZhome.NQ.CommonServices.ConfigData">ConfigData</see> instances with the setting data.</param>
		/// <returns><c>True</c>, if the value is set successfully.</returns>
		bool SetProfileListSetting(string profile, string protocolName, string settingName, System.Collections.Generic.IList<ConfigData> data);

		/// <summary>
		/// Removes a setting of a connection profile from the setting file.
		/// </summary>
		/// <param name="profile">The profile name.</param>
		/// <param name="protocolName">
		/// Name of the protocol, returned by the 
		/// <see cref="AWZhome.NQ.CommonServices.ISession.Protocol">Protocol</see> property of
		/// a session service.
		/// </param>
		/// <param name="settingName">Name of the setting</param>
		/// <returns><c>True</c>, if the setting could be removed successfully.</returns>
		bool RemoveProfileSetting(string profile, string protocolName, string settingName);

		/// <summary>
		/// Removes a list setting of a connection profile from the setting file.
		/// </summary>
		/// <param name="profile">The profile name.</param>
		/// <param name="protocolName">
		/// Name of the protocol, returned by the 
		/// <see cref="AWZhome.NQ.CommonServices.ISession.Protocol">Protocol</see> property of
		/// a session service.
		/// </param>
		/// <param name="settingName">Name of the list setting</param>
		/// <returns><c>True</c>, if the setting could be removed successfully.</returns>
		bool RemoveProfileListSetting(string profile, string protocolName, string settingName);

		/// <summary>
		/// Remove all settings of a NQ component from the setting file.
		/// </summary>
		/// <param name="component">The component name.</param>
		/// <param name="userSettings">Sets if the settings should be removed from the user-specific configuration.</param>
		/// <returns><c>True</c>, if the settings could be removed successfully.</returns>
		bool RemoveComponentSettings(string component, bool userSettings);

		/// <summary>
		/// Returns a NQ component setting.
		/// </summary>
		/// <param name="component">The component name.</param>
		/// <param name="settingName">Name of the setting.</param>
		/// <param name="userSetting">Sets if the setting should be read from the user-specific configuration.</param>
		/// <returns>A <see cref="AWZhome.NQ.CommonServices.ConfigData">ConfigData</see> instance with the setting data.</returns>
		ConfigData GetSetting(string component, string settingName, bool userSetting);

		/// <summary>
		/// Returns a list setting of a NQ component.
		/// </summary>
		/// <param name="component">The component name.</param>
		/// <param name="settingName">Name of the setting.</param>
		/// <param name="userSetting">Sets if the setting should be read from the user-specific configuration.</param>
		/// <returns>A list of <see cref="AWZhome.NQ.CommonServices.ConfigData">ConfigData</see> instances with the setting data.</returns>
		System.Collections.Generic.IList<ConfigData> GetListSetting(string component, string settingName, bool userSetting);

		/// <summary>
		/// Sets the value of a NQ component setting.
		/// </summary>
		/// <param name="component">The component name.</param>
		/// <param name="settingName">Name of the setting.</param>
		/// <param name="data">A <see cref="AWZhome.NQ.CommonServices.ConfigData">ConfigData</see> instance with the setting data.</param>
		/// <param name="userSetting">Sets if the setting should be written to the user-specific configuration.</param>
		/// <returns><c>True</c>, if the value could be set successfully.</returns>
		bool SetSetting(string component, string settingName, ConfigData data, bool userSetting);

		/// <summary>
		/// Sets the list setting of a NQ component.
		/// </summary>
		/// <param name="component">The component name.</param>
		/// <param name="settingName">Name of the setting.</param>
		/// <param name="data">A list of <see cref="AWZhome.NQ.CommonServices.ConfigData">ConfigData</see> instances with the setting data.</param>
		/// <param name="userSetting">Sets if the setting should be written to the user-specific configuration.</param>
		/// <returns><c>True</c>, if the value could be set successfully.</returns>
		bool SetListSetting(string component, string settingName, System.Collections.Generic.IList<ConfigData> data, bool userSetting);

		/// <summary>
		/// Removes a NQ component setting from the setting file.
		/// </summary>
		/// <param name="component">The component name.</param>
		/// <param name="settingName">Name of the setting.</param>
		/// <param name="userSetting">Sets if the setting should be removed from the user-specific configuration.</param>
		/// <returns><c>True</c>, if the setting could be removed successfully.</returns>
		bool RemoveSetting(string component, string settingName, bool userSetting);

		/// <summary>
		/// Removes a NQ component setting from the setting file.
		/// </summary>
		/// <param name="component">The component name.</param>
		/// <param name="settingName">Name of the setting.</param>
		/// <param name="userSetting">Sets if the setting should be removed from the user-specific configuration.</param>
		/// <returns><c>True</c>, if the setting could be removed successfully.</returns>
		bool RemoveListSetting(string component, string settingName, bool userSetting);

		/// <summary>
		/// Returns a container setting.
		/// </summary>
		/// <param name="container">The container name.</param>
		/// <param name="settingName">Name of the setting.</param>
		/// <returns>A <see cref="AWZhome.NQ.CommonServices.ConfigData">ConfigData</see> instance with the setting data.</returns>
		ConfigData GetContainerSetting(string container, string settingName);

		/// <summary>
		/// Returns the data of a container list setting.
		/// </summary>
		/// <param name="container">The container name.</param>
		/// <param name="settingName">Name of the setting.</param>
		/// <returns>A list of <see cref="AWZhome.NQ.CommonServices.ConfigData">ConfigData</see> instances with the setting data.</returns>
		System.Collections.Generic.IList<ConfigData> GetContainerListSetting(string container, string listName);

		/// <summary>
		/// Sets the value of a container setting.
		/// </summary>
		/// <param name="container">The container name.</param>
		/// <param name="settingName">Name of the setting</param>
		/// <param name="data">A <see cref="AWZhome.NQ.CommonServices.ConfigData">ConfigData</see> instance with the setting data.</param>
		/// <returns><c>True</c>, if the value could be set successfully.</returns>
		bool SetContainerSetting(string container, string settingName, ConfigData data);

		/// <summary>
		/// Sets the data of a container list setting.
		/// </summary>
		/// <param name="container">The container name.</param>
		/// <param name="settingName">Name of the setting</param>
		/// <param name="data">A list of <see cref="AWZhome.NQ.CommonServices.ConfigData">ConfigData</see> instances with the setting data.</param>
		/// <returns><c>True</c>, if the list could be set successfully.</returns>
		bool SetContainerListSetting(string container, string settingName, System.Collections.Generic.IList<ConfigData> list);

		/// <summary>
		/// Removes a container setting from setting file.
		/// </summary>
		/// <param name="container">The container name.</param>
		/// <param name="settingName">Name of the setting.</param>
		/// <returns><c>True</c>, if the setting could be removed successfully.</returns>
		bool RemoveContainerSetting(string container, string settingName);

		/// <summary>
		/// Removes a container setting from setting file.
		/// </summary>
		/// <param name="container">The container name.</param>
		/// <param name="settingName">Name of the setting.</param>
		/// <returns><c>True</c>, if the setting could be removed successfully.</returns>
		bool RemoveContainerListSetting(string container, string settingName);

		/// <summary>
		/// Removes all settings of a container from the setting file.
		/// </summary>
		/// <param name="container">The container name.</param>
		/// <returns><c>True</c>, if the settings could be removed successfully.</returns>
		bool RemoveContainerSettings(string container);

		/// <summary>
		/// Loads the configuration from the setting file to the service's internal cache.
		/// </summary>
		/// <remarks>
		/// This method is usually called externally when application starts.
		/// </remarks>
		void LoadConfiguration();

		/// <summary>
		/// Writes the configuration from the service's internal cache to the setting file.
		/// </summary>
		/// <remarks>
		/// The service is responsible for calling this method when it's destroyed.
		/// </remarks>
		void SaveConfiguration();
	}
}
